package com.smart.community.feign.region.service;

import java.util.List;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

import com.smart.community.feign.region.dto.OwnerInfoDTO;
import com.smart.community.feign.region.fallback.OwnerFeignFallbackFactory;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;

/**
 * 业主信息Feign接口
 * 
 * @author Wu.Liang
 * @since 2025-08-20
 * @version 2.0.0
 */
@Tag(name = "业主信息Feign接口", description = "业主信息相关Feign接口")
@FeignClient(
    name = "smart-community-region",
    path = "/region",
    fallbackFactory = OwnerFeignFallbackFactory.class,
    contextId = "ownerFeignService"
)
public interface OwnerFeignService {
    
    /**
     * 根据业主ID获取业主信息
     * 
     * @param ownerId 业主ID
     * @return 业主信息
     */
    @Operation(summary = "根据业主ID获取业主信息")
    @GetMapping("/feign/owner/{ownerId}")
    OwnerInfoDTO getOwnerById(@Parameter(description = "业主ID") @PathVariable("ownerId") Long ownerId);
    
    /**
     * 根据用户ID获取业主信息
     * 
     * @param userId 用户ID
     * @return 业主信息
     */
    @Operation(summary = "根据用户ID获取业主信息")
    @GetMapping("/feign/owner/user/{userId}")
    OwnerInfoDTO getOwnerByUserId(@Parameter(description = "用户ID") @PathVariable("userId") Long userId);
    
    /**
     * 根据身份证号获取业主信息
     * 
     * @param idCard 身份证号
     * @return 业主信息
     */
    @Operation(summary = "根据身份证号获取业主信息")
    @GetMapping("/feign/owner/id-card/{idCard}")
    OwnerInfoDTO getOwnerByIdCard(@Parameter(description = "身份证号") @PathVariable("idCard") String idCard);
    
    /**
     * 根据手机号获取业主信息
     * 
     * @param phone 手机号
     * @return 业主信息
     */
    @Operation(summary = "根据手机号获取业主信息")
    @GetMapping("/feign/owner/phone/{phone}")
    OwnerInfoDTO getOwnerByPhone(@Parameter(description = "手机号") @PathVariable("phone") String phone);
    
    /**
     * 根据房户ID获取关联的业主列表
     * 
     * @param householdId 房户ID
     * @return 业主列表
     */
    @Operation(summary = "根据房户ID获取关联的业主列表")
    @GetMapping("/feign/owner/household/{householdId}")
    List<OwnerInfoDTO> getOwnersByHouseholdId(@Parameter(description = "房户ID") @PathVariable("householdId") Long householdId);
    
    /**
     * 根据社区ID获取业主列表
     * 
     * @param communityId 社区ID
     * @return 业主列表
     */
    @Operation(summary = "根据社区ID获取业主列表")
    @GetMapping("/feign/owner/community/{communityId}")
    List<OwnerInfoDTO> getOwnersByCommunityId(@Parameter(description = "社区ID") @PathVariable("communityId") Long communityId);
    
    /**
     * 根据楼栋ID获取业主列表
     * 
     * @param buildingId 楼栋ID
     * @return 业主列表
     */
    @Operation(summary = "根据楼栋ID获取业主列表")
    @GetMapping("/feign/owner/building/{buildingId}")
    List<OwnerInfoDTO> getOwnersByBuildingId(@Parameter(description = "楼栋ID") @PathVariable("buildingId") Long buildingId);
    
    /**
     * 根据单元ID获取业主列表
     * 
     * @param unitId 单元ID
     * @return 业主列表
     */
    @Operation(summary = "根据单元ID获取业主列表")
    @GetMapping("/feign/owner/unit/{unitId}")
    List<OwnerInfoDTO> getOwnersByUnitId(@Parameter(description = "单元ID") @PathVariable("unitId") Long unitId);
    
    /**
     * 检查业主是否存在
     * 
     * @param ownerId 业主ID
     * @return 是否存在
     */
    @Operation(summary = "检查业主是否存在")
    @GetMapping("/feign/owner/check/{ownerId}")
    Boolean checkOwnerExists(@Parameter(description = "业主ID") @PathVariable("ownerId") Long ownerId);
    
    /**
     * 检查身份证号是否已存在
     * 
     * @param idCard 身份证号
     * @param excludeId 排除的业主ID
     * @return 是否存在
     */
    @Operation(summary = "检查身份证号是否已存在")
    @GetMapping("/feign/owner/check/id-card")
    Boolean checkIdCardExists(
            @Parameter(description = "身份证号") @RequestParam("idCard") String idCard,
            @Parameter(description = "排除的业主ID") @RequestParam(value = "excludeId", required = false) Long excludeId);
    
    /**
     * 检查手机号是否已存在
     * 
     * @param phone 手机号
     * @param excludeId 排除的业主ID
     * @return 是否存在
     */
    @Operation(summary = "检查手机号是否已存在")
    @GetMapping("/feign/owner/check/phone")
    Boolean checkPhoneExists(
            @Parameter(description = "手机号") @RequestParam("phone") String phone,
            @Parameter(description = "排除的业主ID") @RequestParam(value = "excludeId", required = false) Long excludeId);
    
    /**
     * 获取业主关联的房户ID列表
     * 
     * @param userId 用户ID
     * @return 房户ID列表
     */
    @Operation(summary = "获取业主关联的房户ID列表")
    @GetMapping("/feign/owner/household-ids/{userId}")
    List<Long> getOwnerHouseholdIds(@Parameter(description = "用户ID") @PathVariable("userId") Long userId);
    
    /**
     * 根据业主ID获取业主关联的房户ID列表
     * 
     * @param ownerId 业主ID
     * @return 房户ID列表
     */
    @Operation(summary = "根据业主ID获取业主关联的房户ID列表")
    @GetMapping("/feign/owner/household-ids-by-owner/{ownerId}")
    List<Long> getOwnerHouseholdIdsByOwnerId(@Parameter(description = "业主ID") @PathVariable("ownerId") Long ownerId);
    
    /**
     * 根据物业公司ID数组获取业主在物业公司可见范围内的房户ID列表
     * 
     * @param userId 用户ID
     * @param propertyCompanyIds 物业公司ID数组
     * @return 房户ID列表
     */
    @Operation(summary = "根据物业公司ID数组获取业主在物业公司可见范围内的房户ID列表")
    @PostMapping("/feign/owner/household-ids-by-property-companies/{userId}")
    List<Long> getOwnerHouseholdIdsByPropertyCompanies(
            @Parameter(description = "用户ID") @PathVariable("userId") Long userId, 
            @Parameter(description = "物业公司ID数组") @RequestBody List<Long> propertyCompanyIds);
}
